
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Writing an interactive test action &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Writing Health Checks for devices" href="healthchecks.html" />
    <link rel="prev" title="Writing a monitors test action" href="monitors.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/interactive.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Writing an interactive test action</a><ul>
<li><a class="reference internal" href="#advantages-of-interactive-pattern-matching">Advantages of interactive pattern matching</a></li>
<li><a class="reference internal" href="#limits-of-interactive-pattern-matching">Limits of interactive pattern matching</a></li>
<li><a class="reference internal" href="#example-interactive-test-job">Example interactive test job</a></li>
</ul>
</li>
<li><a class="reference internal" href="#combining-different-test-actions">Combining different test actions</a></li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="monitors.html" title="Previous Chapter: Writing a monitors test action"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; Writing a mon...</span>
    </a>
  </li>
  <li>
    <a href="healthchecks.html" title="Next Chapter: Writing Health Checks for devices"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Writing Healt... &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="writing-an-interactive-test-action">
<span id="writing-tests-interactive"></span><span id="index-0"></span><h1>Writing an interactive test action<a class="headerlink" href="#writing-an-interactive-test-action" title="Permalink to this heading">¶</a></h1>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="actions-test.html#interactive-test-action"><span class="std std-ref">Interactive test action reference</span></a></p>
</div>
<p>Parsing test output will always involve some amount of pattern
matching. The test action creates a stream of output, (typically
ASCII), and this needs to be turned into test results either using
scripts on the DUT or after transmission over a serial connection.</p>
<p>Interactive test actions move all of the parsing to the test writer
commands by setting a sequence of strings with expected output and
support for determining failures.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>All interactive test actions need to specify all possible
failure strings for each command, as well as the type of exception
to raise when a string is matched. Interactive test actions must
always have a start and end to the parsing or the entire job will
simply time out because none of the expected matches exist.</p>
</div>
<p>Interactive test actions cannot provide support for monitoring kernel
boot messages or <a class="reference internal" href="writing-tests.html#lava-test-helpers"><span class="std std-ref">LAVA Test Helpers</span></a>, all pattern matching is done
solely by the strings set by the test writer. This rules out support
like <a class="reference internal" href="multinode.html#multinode"><span class="std std-ref">MultiNode</span></a> and <a class="reference internal" href="writing-tests.html#writing-tests-1-0"><span class="std std-ref">Lava-Test Test Definition
1.0</span></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="writing-tests.html#test-definition-portability"><span class="std std-ref">Write portable test definitions</span></a></p>
</div>
<section id="advantages-of-interactive-pattern-matching">
<span id="interactive-advantages"></span><h2>Advantages of interactive pattern matching<a class="headerlink" href="#advantages-of-interactive-pattern-matching" title="Permalink to this heading">¶</a></h2>
<ol class="arabic simple">
<li><p>Keeps pattern matches tightly wrapped around limited sections of
predictable test action output, not across the entire test job or
even the complete test action output.</p></li>
<li><p>Provides methods to execute complex instructions (including
regular expressions) without mangling the syntax due to the
constraints of the submission format (in the case of LAVA, YAML
strings).</p></li>
<li><p>Avoids issues with needing to deploy a set of POSIX scripts to the
<a class="reference internal" href="glossary.html#term-DUT"><span class="xref std std-term">DUT</span></a>, e.g. when the filesystem is inaccessible or read-only
or has access controls like SELinux.</p></li>
<li><p>Allowing test writers to use any arbitrary test output style.</p></li>
<li><p>Includes ability for test writers to raise exceptions based on
specific matches, controlled by the test writer.</p></li>
<li><p>Encourages test writers to create <a class="reference internal" href="writing-tests.html#test-definition-portability"><span class="std std-ref">portable</span></a> custom scripts which are idempotent.
this can make it easier to reproduce failures when reporting bugs
to upstream developers who do not have access to the CI system.</p></li>
</ol>
</section>
<section id="limits-of-interactive-pattern-matching">
<span id="interactive-limits"></span><h2>Limits of interactive pattern matching<a class="headerlink" href="#limits-of-interactive-pattern-matching" title="Permalink to this heading">¶</a></h2>
<ol class="arabic simple">
<li><p>Lacks support for optimizations when specific sections of the test
output comply with a known and strictly enforced format.</p></li>
<li><p>Can be difficult to convert into test action methods which aid
portability. CI becomes difficult for the developers receiving the
bug reports if the developers cannot reproduce the bug without
using the same CI.</p></li>
<li><p>Supporting test jobs with multiple, different, test action
behaviors for each stage of the test operation. For example,
dependency resolution and setup commands could be done with an
overlay and Lava Test Shell Definition whilst running the test to
output a known result format could use a parser specific to that
format.</p></li>
<li><p>Lacks support for versioning of test action components. Test writers
need to implement their own versioning system and ensure that
versions are output into the LAVA test job log file and/or as a
test result.</p></li>
</ol>
</section>
<section id="example-interactive-test-job">
<span id="example-interactive-job"></span><h2>Example interactive test job<a class="headerlink" href="#example-interactive-test-job" title="Permalink to this heading">¶</a></h2>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="nt">device_type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">beaglebone-black</span>
<span class="linenos"> 2</span>
<span class="linenos"> 3</span><span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">run tests in U-Boot</span>
<span class="linenos"> 4</span><span class="nt">timeouts</span><span class="p">:</span>
<span class="linenos"> 5</span><span class="w">  </span><span class="nt">job</span><span class="p">:</span>
<span class="linenos"> 6</span><span class="w">    </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
<span class="linenos"> 7</span><span class="w">  </span><span class="nt">action</span><span class="p">:</span>
<span class="linenos"> 8</span><span class="w">    </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
<span class="linenos"> 9</span><span class="w">  </span><span class="nt">connection</span><span class="p">:</span>
<span class="linenos">10</span><span class="w">    </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
<span class="linenos">11</span><span class="nt">priority</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">medium</span>
<span class="linenos">12</span><span class="nt">visibility</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">public</span>
<span class="linenos">13</span>
<span class="linenos">14</span><span class="nt">metadata</span><span class="p">:</span>
<span class="linenos">15</span><span class="w">  </span><span class="nt">source</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://gitlab.com/lava/lava.git</span>
<span class="linenos">16</span><span class="w">  </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">doc/v2/examples/test-jobs/bbb-uboot-interactive.yaml</span>
<span class="linenos">17</span>
<span class="linenos">18</span><span class="nt">actions</span><span class="p">:</span>
<span class="hll"><span class="linenos">19</span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">boot</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">20</span><span class="w">    </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bootloader</span>
</span><span class="hll"><span class="linenos">21</span><span class="w">    </span><span class="nt">bootloader</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">u-boot</span>
</span><span class="hll"><span class="linenos">22</span><span class="w">    </span><span class="nt">commands</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[]</span>
</span><span class="hll"><span class="linenos">23</span><span class="w">    </span><span class="nt">prompts</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">24</span><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;=&gt;&#39;</span>
</span><span class="linenos">25</span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">test</span><span class="p">:</span>
<span class="linenos">26</span><span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="linenos">27</span><span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4</span>
<span class="hll"><span class="linenos">28</span><span class="w">    </span><span class="nt">interactive</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">29</span><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">network</span>
</span><span class="hll"><span class="linenos">30</span><span class="w">      </span><span class="nt">prompts</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;=&gt;</span><span class="nv"> </span><span class="s">&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;/</span><span class="nv"> </span><span class="s">#</span><span class="nv"> </span><span class="s">&quot;</span><span class="p p-Indicator">]</span>
</span><span class="hll"><span class="linenos">31</span><span class="w">      </span><span class="nt">script</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">32</span><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dhcp</span>
</span><span class="hll"><span class="linenos">33</span><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dhcp</span>
</span><span class="hll"><span class="linenos">34</span><span class="w">        </span><span class="nt">successes</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">35</span><span class="w">        </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">message</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;DHCP</span><span class="nv"> </span><span class="s">client</span><span class="nv"> </span><span class="s">bound</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">address&quot;</span>
</span><span class="hll"><span class="linenos">36</span><span class="w">        </span><span class="nt">failures</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">37</span><span class="w">        </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">message</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;TIMEOUT&quot;</span>
</span><span class="hll"><span class="linenos">38</span><span class="w">          </span><span class="nt">exception</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">InfrastructureError</span>
</span><span class="hll"><span class="linenos">39</span><span class="w">          </span><span class="nt">error</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;dhcp</span><span class="nv"> </span><span class="s">failed&quot;</span>
</span></pre></div>
</div>
<p>Download or view example interactive test job:
<a class="reference external" href="examples/test-jobs/bbb-uboot-interactive.yaml">examples/test-jobs/bbb-uboot-interactive.yaml</a></p>
</section>
</section>
<section id="combining-different-test-actions">
<span id="combining-test-actions"></span><span id="index-1"></span><h1>Combining different test actions<a class="headerlink" href="#combining-different-test-actions" title="Permalink to this heading">¶</a></h1>
<p>In some situations, there can be a need to combine two or more
different types of test action in a single test job. For example,
a POSIX overlay test action to do initial setup, then a <code class="docutils literal notranslate"><span class="pre">monitors</span></code> or
<code class="docutils literal notranslate"><span class="pre">interactive</span></code> test action to parse the output of a specific task.</p>
<p>It is very important to understand that Lava-Test Test Definition 1.0
<strong>cannot</strong> occur more than once in a single test job once any other
test action type is used. If further test actions are required via the
POSIX shell, an interactive test action must be used.</p>
<p>A single Lava-Test Test Definition 1.0 test action can already include
multiple different tests, potentially from different repositories:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1"># TEST_BLOCK</span>
<span class="linenos"> 2</span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">test</span><span class="p">:</span>
<span class="linenos"> 3</span><span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="linenos"> 4</span><span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
<span class="hll"><span class="linenos"> 5</span><span class="w">    </span><span class="nt">definitions</span><span class="p">:</span>
</span><span class="linenos"> 6</span><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">repository</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http://git.linaro.org/lava-team/lava-functional-tests.git</span>
<span class="hll"><span class="linenos"> 7</span><span class="w">      </span><span class="nt">from</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git</span>
</span><span class="linenos"> 8</span><span class="w">      </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lava-test-shell/smoke-tests-basic.yaml</span>
<span class="hll"><span class="linenos"> 9</span><span class="w">      </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">smoke-tests</span>
</span><span class="linenos">10</span><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">repository</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://git.linaro.org/lava-team/lava-functional-tests.git</span>
<span class="hll"><span class="linenos">11</span><span class="w">      </span><span class="nt">from</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git</span>
</span></pre></div>
</div>
<p>It is fully supported to then add an interactive test action:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">test</span><span class="p">:</span>
<span class="linenos"> 2</span><span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="linenos"> 3</span><span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4</span>
<span class="linenos"> 4</span><span class="w">    </span><span class="nt">interactive</span><span class="p">:</span>
<span class="linenos"> 5</span><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">network</span>
<span class="linenos"> 6</span><span class="w">      </span><span class="nt">prompts</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;=&gt;</span><span class="nv"> </span><span class="s">&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;/</span><span class="nv"> </span><span class="s">#</span><span class="nv"> </span><span class="s">&quot;</span><span class="p p-Indicator">]</span>
<span class="linenos"> 7</span><span class="w">      </span><span class="nt">script</span><span class="p">:</span>
<span class="linenos"> 8</span><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dhcp</span>
<span class="linenos"> 9</span><span class="w">        </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dhcp</span>
<span class="linenos">10</span><span class="w">        </span><span class="nt">successes</span><span class="p">:</span>
<span class="linenos">11</span><span class="w">        </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">message</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;DHCP</span><span class="nv"> </span><span class="s">client</span><span class="nv"> </span><span class="s">bound</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">address&quot;</span>
<span class="linenos">12</span><span class="w">        </span><span class="nt">failures</span><span class="p">:</span>
<span class="linenos">13</span><span class="w">        </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">message</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;TIMEOUT&quot;</span>
<span class="linenos">14</span><span class="w">          </span><span class="nt">exception</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">InfrastructureError</span>
<span class="linenos">15</span><span class="w">          </span><span class="nt">error</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;dhcp</span><span class="nv"> </span><span class="s">failed&quot;</span>
</pre></div>
</div>
<p>However, until Test Definition 2.0 is fully scoped and delivered, it
is not possible to add another Lava-Test Test Definition 1.0 action.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This applies within any one <a class="reference internal" href="glossary.html#term-namespace"><span class="xref std std-term">namespace</span></a>, it does not
apply between different <a class="reference internal" href="deploy-lxc.html#namespaces-with-lxc"><span class="std std-ref">namespaces</span></a>.</p>
</div>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>